SPACE 2

home *** CD-ROM | disk | FTP | other *** search

/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / apps / 29 / general / stnetdev.doc < prev next >

Wrap

Text File | 1985-11-19 | 15KB | 324 lines

ST-NET Local Area Network for the Atari ST Programmer's Guide John S. DeMar Quantum Microsystems, Inc. PO Box 179 Liverpool, NY 13088 315-451-7747 Introduction This document is a guide for Atari ST application programmers who wish to include multi-user functions in their software. All Atari ST programmers should understand ST-Net's environment to insure that ST- Net's usage of the system does not interfere with their own. ST-Net offers two levels of networking functions to the user. At the highest level, the user may talk via keyboard to another user ("Phone") or exchange mail messages ("Mailbox"). Since these features are part of a GEM desk accessory, they are accessed through any GEM application. The second level is a transparent usage of peripherals physically connected to another computer on the network. For instance, one hard disk drive and printer may be accessed by several computers. The ST-Net installation program lets the system operator assign priorities to devices and computers to customize the networks efficiency. For the application programmer, ST-Net offers high-level multi-user functions and low-level access to remote ST computers. All calls are made through the 68000 TRAP #9 instruction in assembly language. Also, a library of these routines will be available for Megamax C at no charge. 1.0 Electrical - 5V (6ma) current loop. - Optically isolated. - 31.25 K Baud serial digital data rate. - 1 start bit, 8 data bits, 1 stop bit. - Two-wire data in, two-wire data out, twisted pairs. - Feedthrough at computer for power loss protection. 2.0 Physical - Ring network, data-out to data-in of adjacent computers. - Dual 5-pin DIN connectors at computers. - Dual 4-pin RJ-11 modular interconnect. - Adapter box for DIN to RJ-11 and protect at each computer. 3.0 Protocol 3.1 Command Frame - Byte-oriented command frame as follows: +-----+-----+-----+-----+-----+-----+------+------+-----+-----+ |DSTN#|RTRY#|SRCN#|COMND|ACNTH:ACNTL|ARG#1...ARG#n|CHCKH:CHCKL| +-----+-----+-----+-----+-----+-----+------+------+-----+-----+ 0 1 2 3 4 5 ...n bytes... 6+n 7+n - Minimum command frame size is 8 bytes (no arguments). - Maximum command frame size is 1032 bytes (1024 argument bytes). - DSTN# ranges from 1 to 255 for upto 255 computers on the ring. Destination node for command or zero if global (special case). - RTRY# counts down to 0 for upto 255 attempts at command. Zero signals that the command was aborted. - SRCN# is the source node number for the command frame. Zero is a special case for new node initialization. - COMND requests one of the following operations: 0 --> Initialization request. (See Net Table description.) 1 --> Remote GEMDOS call. (Trap #1) 2 --> Remote AES/VDI call. (Trap #2) 3 --> Remote BIOS call. (TRAP #13) 4 --> Remote XBIOS call. (TRAP #14) 5 --> Remote Line-A call. (A00X ops) 6-15 --> Global Alerts. 16 --> Mail request. 17 --> Open Mailbox. 18 --> Close Mailbox. 19 --> Read Mail. 20 --> Write Mail. 21 --> Delete Mail. 22 --> List Bulletin Files. 23 --> Post Bulletin. 24 --> Read Bulletin. 25 --> Kill Bulletin. 26 --> Ring Phone. 27 --> Phone string out. 28 --> Phone string in. 29 --> Hang-up Phone. 30 --> BBS announce on. 31 --> BBS announce off. 32 --> BBS conference string out. 33 --> BBS conference string in. 34 --> Status Poll (See Net Table description.) 35-63 --> (Future Expansion.) 64 --> File Status 65 --> Lock File (NOT YET IMPLEMENTED) 66 --> Unlock File (NOT YET IMPLEMENTED) 67-127 --> (Future Expansion.) 3.1 Command Frame (con't) - ACNTH and ACNTL is the count in bytes of the argument string. A command may have upto 1024 bytes of input parameters. - CHCKH and CHCKL is the 16-bit CRC for the command frame. If an error occurs, command frame is retransmitted with RTRY# = RTRY# -1 until RTRY# is zero (failed operation). 3.2 Data/Return Frame - Data/Return frames are strictly replies to Command frames and are only sent when a return action is required. - COMND is the same as for command frames except it has 128 added to its value (highest bit on). This protects against data frames being interpreted as command frames. - Data frames requiring more than 1024 bytes will have the true remaining byte count in ACNTH/ACNTH. The actual byte count will be 1024 until the last partial frame is sent. This allows for some level of time sharing on the ring. 4.0 Network Variables 4.1 Net Table The Net Table holds a description of the network environment for each computer on the network, including your own. The table is built at boot time through the Initialization Request call and added to when ever an Initialization Request is received. The table begins with the entry for your computer and ends with the last computer to be added by the Initialization Request call. The Net Table description for your computer is kept in the STNET.SET file and is built by the NETBUILD.PRG program. Each entry in the Net Table has the following structure: struct NETNODE { char node; The node assigned during init, 0 = end. char priority; Priority level set in NETBUILD, 0 = high. char printer; Printer type on this node, 0 = none. long drives; The 'drvbits' accessible by other nodes. char name[16]; Upto 16 char node-name set in NETBUILD. int flags; 16 flags, first five used as follows: 0 == Phone enabled. 1 == Global Mailbox at this node. 2 == Alerts are locked out. 3 == AES/VDI locked out. 4 == BIOS/XBIOS/LINE-A locked out. char flavor; Type of computer. 0 = ST/MIDI, 1=XE/LINK, } 3+ = RS-232 nodes, 128+ = DMA channel nodes. (Only ST/MIDI is implemented for now.) When a computer is turned off, that node remains in the Net Table until that node is accessed. When a command is not acknowledged after its maximum number of retries, the node is removed from the Net table. If a computer is powered down and rebooted, a duplicate copy of its description could be assigned in the Net Table until the old node is accessed and removed. 4.2 Set-up File The STNET.SET file contains specific data describing the owners node configuration. This file is created or recreated by running the installation program called NETBUILD.PRG. The Set-up File contains the following information: NETNODE table_entry; The structure described under Net Table. This info is declared to all other nodes. int retries[128]; List of the maximum retries for each command frame (one byte per command). int showbull; Flag to show bulletins at powerup. int showmail; Flag to show mail at power-up. int mailpath[]; Pathname for your mailbox. Null indicates that mail will be found on the global mail node path under your node name. This file is loaded at power-up and must be on the boot device's main directory as the filename STNET.SET. This file should not be modified without NETBUILD.PRG. 5.0 Programming Libraries 5.1 Transparent Functions ST-Net handles all accesses to floppy disks, hard disks and printers without special programming on the part of the application programmer. This 'transparent' operation allows existing programs to make use of the peripheral-sharing aspect of the network. The GEM Desk Accessory, STNET.ACC, installs the Phone/Mail features for use in any GEM application. Also, this accessory adds a Printer Spooler (background printing) and a Ramdisk (memory disk emulation). Information about other computers on the network is available by selecting this accessory. 5.2 Application Functions The application programmer may use any of the ST-Net primitive commands to make multi-user, multi-computer programs. For instance, many users could enter data into a database system designed to make use of ST-Net. Or, several callers could have a conference on a multi-line Bulletin Board System running on several Atari ST computers. All of the commands shown in the Command frame description are called via TRAP #9. Here's a brief description of each function showing the library function name and arguments for 'C': rgemdos(node,function,argptr) REMOTE GEMDOS CALL rvdi(node,function,argptr) REMOTE VDI CALL raes(node,function,argptr) REMOTE AES CALL rbios(node,function,argptr) REMOTE BIOS CALL rxbios(node,function,argptr) REMOTE XBIOS CALL For each routine: int node; Remote node number. int function; Function/opcode number. long argptr; Pointer to argument list. 5.2 Application Functions (con't) int net_init(); INITIALIZATION REQUEST Builds the Net Table. Returns -1 if init was successful or 0 if it failed. int net_alert(node,alert) NETWORK GLOBAL ALERTS int node; 0 = Error! Network is disconnected! int alert; 1 = Error! That computer is disconnected! 2 = The Network is busy! 3 = That computer is busy! 4 = Your printer is off line! 5 = Your disk drive is not responding! 6-9 = (Reserved) int net_mailreq(node) MAIL REQUEST int node; Returns -1 if Mailbox is active. Returns 0 if no mailbox for that node. int net_openmail(node) OPEN MAILBOX int node; Activates the mailbox file for the following operations. int net_closemail(node) CLOSE MAILBOX int node; Close the mailbox file if opened. int net_readmail(node,psearch,pmsg) READ MAIL int node; Read a mail message using the char *psearch; search criteria in string psearch. char *pmsg; Save into memory at pmsg. int net_writemail(node,pmsg) WRITE MAIL int node; Write a mail message pointed to by char *pmsg; pmsg. First line of message is subject. int net_delmail(node,psearch,pmsg) DELETE MAIL int node; Delete a mail message matching char *psearch; the subject in psearch. Oldest is deleted if more that one matches. int net_listbull(node,pbuff) LIST BULLETINS int node; List the filenames of bulletins int *pbuff; and save in 'pbuff'. int net_postbull(node,pfile) POST BULLETIN int node; Post a general bulletin saved in the char *pfile; filename 'pfile'. int net_readbull(node,pname,pbuff) READ BULLETIN int node; Read the bulletin 'pname' and save char *pname; into 'pbuff'. Returns the count of char *pbuff; the bytes, 0 means end of bulletin. 5.2 Application Functions (con't) int net_killbull(node,pname) KILL BULLETIN int node; Kills (Deletes) the bulletin in file char *pname; 'pname'. Requires priority of zero. int net_phonecall(node) RING PHONE int node; Alerts a user with a phone call dialog. Returns -1 if accepted, 0 if cancelled. int net_phoneout(node,pmsg) PHONE MESSAGE OUT int node; Send 'pmsg' intended as a line of char *pmsg; conversation. Node 0 sends to all nodes. Maximum length of 1024 bytes for 'pmsg'. int net_phonein(node,pmsg) PHONE MESSAGE IN int node; Receive phone message and/or status. char *pmsg; Returns -1 for hangup or the length of the message string saved in 'pmsg'. int net_phoneoff(node) HANG-UP PHONE int node; "Hang-up" your phone and notify the caller at 'node'. 0 means all nodes. int net_bbson(pname) BBS ANNOUNCE LOG ON char *pname; For Bulletin Board software, tell all nodes that a user has logged on and is called 'pname'. int net_bbsoff(); BBS ANNOUNCE LOG OFF For Bulletin Board software, tell all nodes that your user logged off. int net_bbsout(node,pmsg) BBS CONFERENCE MESSAGE OUT int node; Send conference message in bulletin char *pmsg; board software. Node 0 sends to all. int net_bbsin(node,pmsg) BBS CONFERENCE MESSAGE IN int node; Check for a conference message in char *pmsg; bulletin board software. Message is saved in 'pmsg' and returns the length of message. int net_status(node,pnet) CHECK NETWORK STATUS int node; Copies the net table entry for 'node' NETNODE *pnet; into 'pnet'. Also returns a -1 if the node is busy or 0 if it is not. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;